package com.maiko.maikoaiagent.rag;

import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.chat.client.advisor.RetrievalAugmentationAdvisor;
import org.springframework.ai.chat.client.advisor.api.Advisor;
import org.springframework.ai.rag.retrieval.search.DocumentRetriever;
import org.springframework.ai.rag.retrieval.search.VectorStoreDocumentRetriever;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.filter.Filter;
import org.springframework.ai.vectorstore.filter.FilterExpressionBuilder;

/**
 * LoveApp RAG（检索增强生成）自定义顾问工厂类
 *
 * 该类用于创建一个基于向量检索的自定义顾问（Advisor）实例，
 * 结合指定的向量存储和状态过滤条件，生成检索增强组件。
 *
 * 功能说明：
 * - 通过传入的 VectorStore 和状态字符串，构造带过滤条件的 DocumentRetriever。
 * - 设置相似度阈值和返回文档的数量（topK）。
 * - 最终返回一个 RetrievalAugmentationAdvisor 实例，作为 RAG 框架中的增强组件。
 *
 * 适用场景：
 * 结合业务状态（如“单身”、“已婚”等）过滤文档，
 * 只从符合条件的文档中进行相似度检索，提升检索结果的相关性和准确度。
 *
 * @author Maiko7
 * @create 2025-07-09 10:39
 */
@Slf4j
public class LoveAppRagCustomAdvisorFactory {

    /**
     * 创建一个带自定义过滤条件的 RAG 检索增强顾问（Advisor）
     *
     * @param vectorStore 用于向量检索的存储实例
     * @param status      业务状态过滤条件，例如 "active", "published" 等
     * @return 构建好的 Advisor 实例，内含基于向量检索且带状态过滤的文档检索器
     */
    public static Advisor createLoveAppRagCustomAdvisor(VectorStore vectorStore, String status) {
        // 构造过滤表达式，限制只检索符合给定状态的文档
        Filter.Expression expression = new FilterExpressionBuilder()
                .eq("status", status) // 等于条件：status 字段匹配传入的 status 参数
                .build();

        // 创建文档检索器，设置向量存储、过滤条件、相似度阈值和返回数量
        DocumentRetriever documentRetriever = VectorStoreDocumentRetriever.builder()
                .vectorStore(vectorStore)               // 绑定向量存储实例
                .filterExpression(expression)           // 应用过滤表达式
                .similarityThreshold(0.5)                // 设置相似度阈值，过滤相似度过低的结果
                .topK(3)                                // 返回最相似的前三个文档
                .build();

        // 构建一个 RetrievalAugmentationAdvisor 实例，集成文档检索和查询增强功能
        return RetrievalAugmentationAdvisor.builder()
                .documentRetriever(documentRetriever)   // 设置用于检索相关文档的文档检索器
                .queryAugmenter(LoveAppContextualQueryAugmenterFactory.createInstance())     // 设置查询增强器，用于对用户查询进行上下文增强和空上下文提示
                .build();   // 构建最终的 Advisor 对象
    }
}


